<div id="Keyword-substitution"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[cvs: Revision management#When-to-commit  &lt; ]|</td>
<td valign="middle" align="left">|[[#Keyword-list| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[cvs: Revision management#Revision-management  &lt;&lt; ]|</td>
<td valign="middle" align="left">|[[cvs#Top| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Tracking third-party sources#Tracking-sources  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Keyword-substitution-1"></div>
== Keyword substitution ==
<div id="index-Keyword-substitution"></div>
<div id="index-Keyword-expansion"></div>
<div id="index-Identifying-files"></div>


<p>As long as you edit source files inside a working
directory you can always find out the state of
your files via &lsquo;<samp>cvs status</samp>&rsquo; and &lsquo;<samp>cvs log</samp>&rsquo;.
But as soon as you export the files from your
development environment it becomes harder to identify
which revisions they are.
</p>
<p><small>CVS</small> can use a mechanism known as <em>keyword
substitution</em> (or <em>keyword expansion</em>) to help
identifying the files.  Embedded strings of the form
<code>$<var>keyword</var>$</code> and
<code>$<var>keyword</var>:&hellip;$</code> in a file are replaced
with strings of the form
<code>$<var>keyword</var>:<var>value</var>$</code> whenever you obtain
a new revision of the file.
</p>
<pre class="menu-preformatted"><nowiki></nowiki>&bull;[[#Keyword-list| Keyword list]]::<nowiki>                   Keywords
</nowiki>&bull;[[#Using-keywords| Using keywords]]::<nowiki>                 Using keywords
</nowiki>&bull;[[#Avoiding-substitution| Avoiding substitution]]::<nowiki>          Avoiding substitution
</nowiki>&bull;[[#Substitution-modes| Substitution modes]]::<nowiki>             Substitution modes
</nowiki>&bull;[[#Configuring-keyword-expansion| Configuring keyword expansion]]::<nowiki>  Configuring keyword expansion
</nowiki>&bull;[[#Log-keyword| Log keyword]]::<nowiki>                    Problems with the $<i></i>Log$ keyword.
</nowiki></pre>
<hr size="6">
<div id="Keyword-list"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Keyword-substitution| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Using-keywords| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Keyword-substitution| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Keyword-substitution| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Tracking third-party sources#Tracking-sources  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Keyword-List"></div>
=== Keyword List ===
<div id="index-Keyword-List"></div>


<p>This is a list of the keywords:
</p>
<dl compact="compact">
<dd><div id="index-Author-keyword"></div>
</dd>
<dt> <code>$<i></i>Author$</code></dt>
<dd><p>The login name of the user who checked in the revision.
</p>
<div id="index-CVSHeader-keyword"></div>
</dd>
<dt> <code>$<i></i>CVSHeader</code></dt>
<dd><p>A standard header (similar to $<i></i>Header$, but with
the CVS root stripped off). It contains the relative
pathname of the <small>RCS</small> file to the CVS root, the
revision number, the date (UTC), the author, the state,
and the locker (if locked). Files will normally never
be locked when you use <small>CVS</small>.
</p>
<p>Note that this keyword has only been recently
introduced to <small>CVS</small> and may cause problems with
existing installations if $<i></i>CVSHeader$ is already
in the files for a different purpose. This keyword may
be excluded using the <code>KeywordExpansion=eCVSHeader</code>
in the &lsquo;<tt>CVSROOT/config</tt>&rsquo; file. 
See [[#Configuring-keyword-expansion|Configuring Keyord Expansion]] for more details.
</p>
<div id="index-Date-keyword"></div>
</dd>
<dt> <code>$<i></i>Date$</code></dt>
<dd><p>The date and time (UTC) the revision was checked in.
</p>
<div id="index-Header-keyword"></div>
</dd>
<dt> <code>$<i></i>Header$</code></dt>
<dd><p>A standard header containing the full pathname of the
<small>RCS</small> file, the revision number, the date (UTC), the
author, the state, and the locker (if locked).  Files
will normally never be locked when you use <small>CVS</small>.
</p>
<div id="index-Id-keyword"></div>
</dd>
<dt> <code>$<i></i>Id$</code></dt>
<dd><p>Same as <code>$<i></i>Header$</code>, except that the <small>RCS</small>
filename is without a path.
</p>
<div id="index-Name-keyword"></div>
</dd>
<dt> <code>$<i></i>Name$</code></dt>
<dd><p>Tag name used to check out this file.  The keyword is
expanded only if one checks out with an explicit tag
name.  For example, when running the command <code>cvs
co -r first</code>, the keyword expands to &lsquo;<samp>Name: first</samp>&rsquo;.
</p>
<div id="index-Locker-keyword"></div>
</dd>
<dt> <code>$<i></i>Locker$</code></dt>
<dd><p>The login name of the user who locked the revision
(empty if not locked, which is the normal case unless
<code>cvs admin -l</code> is in use).
</p>
<div id="index-Log-keyword"></div>
</dd>
<dt> <code>$<i></i>Log$</code></dt>
<dd><p>The log message supplied during commit, preceded by a
header containing the <small>RCS</small> filename, the revision
number, the author, and the date (UTC).  Existing log
messages are <em>not</em> replaced.  Instead, the new log
message is inserted after <code>$<i></i>Log:&hellip;$</code>.
Each new line is prefixed with the same string which
precedes the <code>$Log</code> keyword.  For example, if the
file contains:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>  /* Here is what people have been up to:
   *
   * $<i></i>Log: frob.c,v $
   * Revision 1.1  1997/01/03 14:23:51  joe
   * Add the superfrobnicate option
   *
   */
</nowiki></pre></td></tr></table>

<p>then additional lines which are added when expanding
the <code>$Log</code> keyword will be preceded by &lsquo;<samp>   * </samp>&rsquo;.
Unlike previous versions of <small>CVS</small> and <small>RCS</small>, the
<em>comment leader</em> from the <small>RCS</small> file is not used.
The <code>$Log</code> keyword is useful for
accumulating a complete change log in a source file,
but for several reasons it can be problematic.
See section [[#Log-keyword|Problems with the $<i></i>Log$ keyword.]].
</p>
<div id="index-RCSfile-keyword"></div>
</dd>
<dt> <code>$<i></i>RCSfile$</code></dt>
<dd><p>The name of the RCS file without a path.
</p>
<div id="index-Revision-keyword"></div>
</dd>
<dt> <code>$<i></i>Revision$</code></dt>
<dd><p>The revision number assigned to the revision.
</p>
<div id="index-Source-keyword"></div>
</dd>
<dt> <code>$<i></i>Source$</code></dt>
<dd><p>The full pathname of the RCS file.
</p>
<div id="index-State-keyword"></div>
</dd>
<dt> <code>$<i></i>State$</code></dt>
<dd><p>The state assigned to the revision.  States can be
assigned with <code>cvs admin -s</code>&mdash;see [cvs: Guide to CVS commands#admin-options admin options].
</p>
<div id="index-Local-keyword"></div>
</dd>
<dt> <code>Local keyword</code></dt>
<dd><p>The <code>LocalKeyword</code> option in the &lsquo;<tt>CVSROOT/config</tt>&rsquo; file
may be used to specify a local keyword which is to be
used as an alias for one of the other keywords. For
example, if the &lsquo;<tt>CVSROOT/config</tt>&rsquo; file contains
a line with <code>LocalKeyword=MYBSD=CVSHeader</code>, then a
file with the local keyword $<i></i>MYBSD$ will be
expanded as if it were a $<i></i>CVSHeader$ keyword. If
the src/frob.c file contained this keyword, it might
look something like this:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>  /*
   * $<i></i>MYBSD: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $ 
   */
</nowiki></pre></td></tr></table>

<p>Many repositories make use of a such a &ldquo;local
keyword&rdquo; feature. An old patch to <small>CVS</small> provided
the <code>LocalKeyword</code> feature using a <code>tag=</code>
option and called this the &ldquo;custom tag&rdquo; or &ldquo;local
tag&rdquo; feature. It was used in conjunction with the
what they called the <code>tagexpand=</code> option. In
<small>CVS</small> this other option is known as the
<code>KeywordExpand</code> option. 
See [[#Configuring-keyword-expansion|Configuring Keyord Expansion]] for more
details.
</p>
<p>Examples from popular projects include:
$<i></i>FreeBSD$, $<i></i>NetBSD$,
$<i></i>OpenBSD$, $<i></i>XFree86$,
$<i></i>Xorg$.
</p>
<p>The advantage of this is that you can include your
local version information in a file using this local
keyword without disrupting the upstream version
information (which may be a different local keyword or
a standard keyword). Allowing bug reports and the like
to more properly identify the source of the original
bug to the third-party and reducing the number of
conflicts that arise during an import of a new version.
</p>
<p>All keyword expansion except the local keyword may be
disabled using the <code>KeywordExpansion</code> option in
the &lsquo;<tt>CVSROOT/config</tt>&rsquo; file&mdash;see 
[[#Configuring-keyword-expansion|Configuring Keyord Expansion]] for more details.
</p>
</dd>
</dl>

<hr size="6">
<div id="Using-keywords"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Keyword-list| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Avoiding-substitution| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Keyword-substitution| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Keyword-substitution| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Tracking third-party sources#Tracking-sources  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Using-keywords-1"></div>
=== Using keywords ===

<p>To include a keyword string you simply include the
relevant text string, such as <code>$<i></i>Id$</code>, inside the
file, and commit the file.  <small>CVS</small> will automatically
expand the string as part of the commit operation.
</p>
<p>It is common to embed the <code>$<i></i>Id$</code> string in
the source files so that it gets passed through to
generated files.  For example, if you are managing
computer program source code, you might include a
variable which is initialized to contain that string.
Or some C compilers may provide a <code>#pragma ident</code>
directive.  Or a document management system might
provide a way to pass a string through to generated
files.
</p>

<div id="index-Ident-_0028shell-command_0029"></div>
<p>The <code>ident</code> command (which is part of the <small>RCS</small>
package) can be used to extract keywords and their
values from a file.  This can be handy for text files,
but it is even more useful for extracting keywords from
binary files.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>$ ident samp.c
samp.c:
     $<i></i>Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
$ gcc samp.c
$ ident a.out
a.out:
     $<i></i>Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
</nowiki></pre></td></tr></table>

<div id="index-What-_0028shell-command_0029"></div>
<p>S<small>CCS</small> is another popular revision control system.
It has a command, <code>what</code>, which is very similar to
<code>ident</code> and used for the same purpose.  Many sites
without <small>RCS</small> have <small>SCCS</small>.  Since <code>what</code>
looks for the character sequence <code>@(#)</code> it is
easy to include keywords that are detected by either
command.  Simply prefix the keyword with the
magic <small>SCCS</small> phrase, like this:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>static char *id=&quot;@(#) $<i></i>Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $&quot;;
</nowiki></pre></td></tr></table>

<hr size="6">
<div id="Avoiding-substitution"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Using-keywords| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Substitution-modes| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Keyword-substitution| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Keyword-substitution| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Tracking third-party sources#Tracking-sources  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Avoiding-substitution-1"></div>
=== Avoiding substitution ===

<p>Keyword substitution has its disadvantages.  Sometimes
you might want the literal text string
&lsquo;<samp>$<i></i>Author$</samp>&rsquo; to appear inside a file without
<small>CVS</small> interpreting it as a keyword and expanding it
into something like &lsquo;<samp>$<i></i>Author: ceder $</samp>&rsquo;.
</p>
<p>There is unfortunately no way to selectively turn off
keyword substitution.  You can use &lsquo;<samp>-ko</samp>&rsquo;
(see section [[#Substitution-modes|Substitution modes]]) to turn off keyword
substitution entirely.
</p>
<p>In many cases you can avoid using keywords in
the source, even though they appear in the final
product.  For example, the source for this manual
contains &lsquo;<samp>$@asis{}Author$</samp>&rsquo; whenever the text
&lsquo;<samp>$<i></i>Author$</samp>&rsquo; should appear.  In <code>nroff</code>
and <code>troff</code> you can embed the null-character
<code>\&amp;</code> inside the keyword for a similar effect.
</p>
<p>It is also possible to specify an explicit list of
keywords to include or exclude using the
<code>KeywordExpand</code> option in the
&lsquo;<tt>CVSROOT/config</tt>&rsquo; file&ndash;see [[#Configuring-keyword-expansion|Configuring Keyord Expansion]]
for more details. This feature is intended primarily
for use with the <code>LocalKeyword</code> option&ndash;see
[[#Keyword-list|Keyword List]].
</p>
<hr size="6">
<div id="Substitution-modes"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Avoiding-substitution| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Configuring-keyword-expansion| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Keyword-substitution| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Keyword-substitution| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Tracking third-party sources#Tracking-sources  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Substitution-modes-1"></div>
=== Substitution modes ===
<div id="index-Keyword-substitution_002c-changing-modes"></div>
<div id="index-_002dk-_0028keyword-substitution_0029"></div>
<div id="index-Kflag"></div>

<p>Each file has a stored default substitution mode, and
each working directory copy of a file also has a
substitution mode.  The former is set by the &lsquo;<samp>-k</samp>&rsquo;
option to <code>cvs add</code> and <code>cvs admin</code>; the
latter is set by the &lsquo;<samp>-k</samp>&rsquo; or &lsquo;<samp>-A</samp>&rsquo; options to <code>cvs
checkout</code> or <code>cvs update</code>.  <code>cvs diff</code> also
has a &lsquo;<samp>-k</samp>&rsquo; option.  For some examples,
see [cvs: Handling binary files#Binary-files Handling binary files], and [cvs: Branching and merging#Merging-and-keywords Merging and keywords].
</p>
<p>The modes available are:
</p>
<dl compact="compact">
<dt> &lsquo;<samp>-kkv</samp>&rsquo;</dt>
<dd><p>Generate keyword strings using the default form, e.g.
<code>$<i></i>Revision: 5.7 $</code> for the <code>Revision</code>
keyword.
</p>
</dd>
<dt> &lsquo;<samp>-kkvl</samp>&rsquo;</dt>
<dd><p>Like &lsquo;<samp>-kkv</samp>&rsquo;, except that a locker&rsquo;s name is always
inserted if the given revision is currently locked.
The locker&rsquo;s name is only relevant if <code>cvs admin
-l</code> is in use.
</p>
</dd>
<dt> &lsquo;<samp>-kk</samp>&rsquo;</dt>
<dd><p>Generate only keyword names in keyword strings; omit
their values.  For example, for the <code>Revision</code>
keyword, generate the string <code>$<i></i>Revision$</code>
instead of <code>$<i></i>Revision: 5.7 $</code>.  This option
is useful to ignore differences due to keyword
substitution when comparing different revisions of a
file (see section [cvs: Branching and merging#Merging-and-keywords Merging and keywords]).
</p>
</dd>
<dt> &lsquo;<samp>-ko</samp>&rsquo;</dt>
<dd><p>Generate the old keyword string, present in the working
file just before it was checked in.  For example, for
the <code>Revision</code> keyword, generate the string
<code>$<i></i>Revision: 1.1 $</code> instead of
<code>$<i></i>Revision: 5.7 $</code> if that is how the
string appeared when the file was checked in.
</p>
</dd>
<dt> &lsquo;<samp>-kb</samp>&rsquo;</dt>
<dd><p>Like &lsquo;<samp>-ko</samp>&rsquo;, but also inhibit conversion of line
endings between the canonical form in which they are
stored in the repository (linefeed only), and the form
appropriate to the operating system in use on the
client.  For systems, like unix, which use linefeed
only to terminate lines, this is very similar to
&lsquo;<samp>-ko</samp>&rsquo;.  For more information on binary files, see
[cvs: Handling binary files#Binary-files Handling binary files].  In <small>CVS</small> version 1.12.2 and later
&lsquo;<samp>-kb</samp>&rsquo;, as set by <code>cvs add</code>, <code>cvs admin</code>, or
<code>cvs import</code> may not be overridden by a &lsquo;<samp>-k</samp>&rsquo; option
specified on the command line.
</p>
</dd>
<dt> &lsquo;<samp>-kv</samp>&rsquo;</dt>
<dd><p>Generate only keyword values for keyword strings.  For
example, for the <code>Revision</code> keyword, generate the string
<code>5.7</code> instead of <code>$<i></i>Revision: 5.7 $</code>.
This can help generate files in programming languages
where it is hard to strip keyword delimiters like
<code>$<i></i>Revision: $</code> from a string.  However,
further keyword substitution cannot be performed once
the keyword names are removed, so this option should be
used with care.
</p>
<p>One often would like to use &lsquo;<samp>-kv</samp>&rsquo; with <code>cvs
export</code>&mdash;see section [cvs: Guide to CVS commands#export export&mdash;Export sources from CVS, similar to checkout].  But be aware that doesn&rsquo;t
handle an export containing binary files correctly.
</p>
</dd>
</dl>

<hr size="6">
<div id="Configuring-keyword-expansion"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Substitution-modes| &lt; ]]|</td>
<td valign="middle" align="left">|[[#Log-keyword| &gt; ]]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Keyword-substitution| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Keyword-substitution| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Tracking third-party sources#Tracking-sources  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Configuring-Keyord-Expansion"></div>
=== Configuring Keyord Expansion ===
<div id="index-Configuring-keyword-expansion"></div>

<p>In a repository that includes third-party software on
vendor branches, it is sometimes helpful to configure
CVS to use a local keyword instead of the standard
$<i></i>Id$ or $<i></i>Header$ keywords. Examples from
real projects includ, $<i></i>Xorg$, $<i></i>XFree86$,
$<i></i>FreeBSD$, $<i></i>NetBSD$,
$<i></i>OpenBSD$, and even $<i></i>dotat$.
The advantage of this is that
you can include your local version information in a
file using this local keyword (sometimes called a
&ldquo;custom tag&rdquo; or a &ldquo;local tag&rdquo;) without disrupting
the upstream version information (which may be a
different local keyword or a standard keyword). In
these cases, it is typically desirable to disable the
expansion of all keywords except the configured local
keyword.
</p>
<p>The <code>KeywordExpansion</code> option in the
&lsquo;<tt>CVSROOT/config</tt>&rsquo; file is intended to allow for the
either the explicit exclusion of a keyword or list of
keywords, or for the explicit inclusion of a keyword or
a list of keywords. This list may include the
<code>LocalKeyword</code> that has been configured.
</p>
<p>The <code>KeywordExpansion</code> option is followed by
<code>=</code> and the next character may either be <code>i</code>
to start an inclusion list or <code>e</code> to start an
exclusion list. If the following lines were added to
the &lsquo;<tt>CVSROOT/config</tt>&rsquo; file:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>        # Add a &quot;MyBSD&quot; keyword and restrict keyword
        # expansion
        LocalKeyword=MyBSD=CVSHeader
        KeywordExpand=iMyBSD
</nowiki></pre></td></tr></table>

<p>then only the $<i></i>MyBSD$ keyword would be expanded.
A list may be used. The this example:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>        # Add a &quot;MyBSD&quot; keyword and restrict keyword
        # expansion to the MyBSD, Name and Date keywords.
        LocalKeyword=MyBSD=CVSHeader
        KeywordExpand=iMyBSD,Name,Date
</nowiki></pre></td></tr></table>

<p>would allow $<i></i>MyBSD$, $<i></i>Name$, and
$<i></i>Date$ to be expanded.
</p>
<p>It is also possible to configure an exclusion list
using the following:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>        # Do not expand the non-RCS keyword CVSHeader
        KeywordExpand=eCVSHeader
</nowiki></pre></td></tr></table>

<p>This allows <small>CVS</small> to ignore the recently introduced
$<i></i>CVSHeader$ keyword and retain all of the
others. The exclusion entry could also contain the
standard RCS keyword list, but this could be confusing
to users that expect RCS keywords to be expanded, so
ycare should be taken to properly set user expectations
for a repository that is configured in that manner.
</p>
<p>If there is a desire to not have any RCS keywords
expanded and not use the <code>-ko</code> flags everywhere,
an administrator may disable all keyword expansion
using the &lsquo;<tt>CVSROOT/config</tt>&rsquo; line:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example"><nowiki>	# Do not expand any RCS keywords
	KeywordExpand=i
</nowiki></pre></td></tr></table>

<p>this could be confusing to users that expect RCS
keywords like $<i></i>Id$ to be expanded properly,
so care should be taken to properly set user
expectations for a repository so configured.
</p>
<p>It should be noted that a patch to provide both the
<code>KeywordExpand</code> and <code>LocalKeyword</code> features
has been around a long time. However, that patch
implemented these features using <code>tag=</code> and
<code>tagexpand=</code> keywords and those keywords are NOT
recognized.
</p>
<hr size="6">
<div id="Log-keyword"></div>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Configuring-keyword-expansion| &lt; ]]|</td>
<td valign="middle" align="left">|[cvs: Tracking third-party sources#Tracking-sources  &gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[#Keyword-substitution| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[[#Keyword-substitution| Up ]]|</td>
<td valign="middle" align="left">|[cvs: Tracking third-party sources#Tracking-sources  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
<div id="Problems-with-the-_0024Log_0024-keyword_002e"></div>
=== Problems with the $<i></i>Log$ keyword. ===

<p>The <code>$<i></i>Log$</code> keyword is somewhat
controversial.  As long as you are working on your
development system the information is easily accessible
even if you do not use the <code>$<i></i>Log$</code>
keyword&mdash;just do a <code>cvs log</code>.  Once you export
the file the history information might be useless
anyhow.
</p>
<p>A more serious concern is that <small>CVS</small> is not good at
handling <code>$<i></i>Log$</code> entries when a branch is
merged onto the main trunk.  Conflicts often result
from the merging operation.
</p>
<p>People also tend to &quot;fix&quot; the log entries in the file
(correcting spelling mistakes and maybe even factual
errors).  If that is done the information from
<code>cvs log</code> will not be consistent with the
information inside the file.  This may or may not be a
problem in real life.
</p>
<p>It has been suggested that the <code>$<i></i>Log$</code>
keyword should be inserted <em>last</em> in the file, and
not in the files header, if it is to be used at all.
That way the long list of change messages will not
interfere with everyday source file browsing.
</p>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">|[[#Keyword-substitution| &lt;&lt; ]]|</td>
<td valign="middle" align="left">|[cvs: Tracking third-party sources#Tracking-sources  &gt;&gt; ]|</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">|[[cvs#Top|Top]]|</td>
<td valign="middle" align="left">|[cvs: Table of Contents#SEC_Contents Contents]|</td>
<td valign="middle" align="left">|[cvs: Index#Index Index]|</td>
<td valign="middle" align="left">|[cvs: About this Manual#SEC_About  ? ]|</td>
</tr></table>
This document was generated by <em>a tester</em> on <em>a sunny day</em> using [http://www.nongnu.org/texi2html/ <em>texi2html</em>].
